home *** CD-ROM | disk | FTP | other *** search
/ Australian Personal Computer 2002 November / CD 1 / APC0211D1.ISO / workshop / prog / files / ActivePerl-5.6.1.633-MSWin32.msi / _67c1e4111f2d056f91011071ec471392 < prev    next >
Encoding:
Text File  |  2001-09-04  |  43.2 KB  |  1,592 lines
  1. package Pod::LaTeX;
  2.  
  3. # Copyright (C) 2000 by Tim Jenness <t.jenness@jach.hawaii.edu>
  4. # All Rights Reserved.
  5.  
  6. =head1 NAME
  7.  
  8. Pod::LaTeX - Convert Pod data to formatted Latex
  9.  
  10. =head1 SYNOPSIS
  11.  
  12.   use Pod::LaTeX;
  13.   my $parser = Pod::LaTeX->new ( );
  14.  
  15.   $parser->parse_from_filehandle;
  16.  
  17.   $parser->parse_from_file ('file.pod', 'file.tex');
  18.  
  19. =head1 DESCRIPTION
  20.  
  21. C<Pod::LaTeX> is a module to convert documentation in the Pod format
  22. into Latex. The L<B<pod2latex>|pod2latex> X<pod2latex> command uses
  23. this module for translation.
  24.  
  25. C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>.
  26.  
  27. =cut
  28.  
  29.  
  30. use strict;
  31. require Pod::ParseUtils;
  32. use base qw/ Pod::Select /;
  33.  
  34. # use Data::Dumper; # for debugging
  35. use Carp;
  36.  
  37. use vars qw/ $VERSION %HTML_Escapes @LatexSections /;
  38.  
  39. $VERSION = '0.53';
  40.  
  41. # Definitions of =headN -> latex mapping
  42. @LatexSections = (qw/
  43.           chapter
  44.           section
  45.           subsection
  46.           subsubsection
  47.           paragraph
  48.           subparagraph
  49.           /);
  50.  
  51. # Standard escape sequences converted to Latex
  52. # Up to "yuml" these are taken from the original pod2latex
  53. # command written by Taro Kawagish (kawagish@imslab.co.jp)
  54.  
  55. %HTML_Escapes = (
  56.     'amp'       =>      '&',      #   ampersand
  57.     'lt'        =>      '$<$',    #   ' left chevron, less-than
  58.     'gt'        =>      '$>$',    #   ' right chevron, greater-than
  59.     'quot'      =>      '"',      #   double quote
  60.     'sol'       =>      '/',
  61.     'verbar'    =>      '$|$',
  62.  
  63.     "Aacute"    =>      "\\'{A}",       #   capital A, acute accent
  64.     "aacute"    =>      "\\'{a}",       #   small a, acute accent
  65.     "Acirc"     =>      "\\^{A}",       #   capital A, circumflex accent
  66.     "acirc"     =>      "\\^{a}",       #   small a, circumflex accent
  67.     "AElig"     =>      '\\AE',         #   capital AE diphthong (ligature)
  68.     "aelig"     =>      '\\ae',         #   small ae diphthong (ligature)
  69.     "Agrave"    =>      "\\`{A}",       #   capital A, grave accent
  70.     "agrave"    =>      "\\`{a}",       #   small a, grave accent
  71.     "Aring"     =>      '\\u{A}',       #   capital A, ring
  72.     "aring"     =>      '\\u{a}',       #   small a, ring
  73.     "Atilde"    =>      '\\~{A}',       #   capital A, tilde
  74.     "atilde"    =>      '\\~{a}',       #   small a, tilde
  75.     "Auml"      =>      '\\"{A}',       #   capital A, dieresis or umlaut mark
  76.     "auml"      =>      '\\"{a}',       #   small a, dieresis or umlaut mark
  77.     "Ccedil"    =>      '\\c{C}',       #   capital C, cedilla
  78.     "ccedil"    =>      '\\c{c}',       #   small c, cedilla
  79.     "Eacute"    =>      "\\'{E}",       #   capital E, acute accent
  80.     "eacute"    =>      "\\'{e}",       #   small e, acute accent
  81.     "Ecirc"     =>      "\\^{E}",       #   capital E, circumflex accent
  82.     "ecirc"     =>      "\\^{e}",       #   small e, circumflex accent
  83.     "Egrave"    =>      "\\`{E}",       #   capital E, grave accent
  84.     "egrave"    =>      "\\`{e}",       #   small e, grave accent
  85.     "ETH"       =>      '\\OE',         #   capital Eth, Icelandic
  86.     "eth"       =>      '\\oe',         #   small eth, Icelandic
  87.     "Euml"      =>      '\\"{E}',       #   capital E, dieresis or umlaut mark
  88.     "euml"      =>      '\\"{e}',       #   small e, dieresis or umlaut mark
  89.     "Iacute"    =>      "\\'{I}",       #   capital I, acute accent
  90.     "iacute"    =>      "\\'{i}",       #   small i, acute accent
  91.     "Icirc"     =>      "\\^{I}",       #   capital I, circumflex accent
  92.     "icirc"     =>      "\\^{i}",       #   small i, circumflex accent
  93.     "Igrave"    =>      "\\`{I}",       #   capital I, grave accent
  94.     "igrave"    =>      "\\`{i}",       #   small i, grave accent
  95.     "Iuml"      =>      '\\"{I}',       #   capital I, dieresis or umlaut mark
  96.     "iuml"      =>      '\\"{i}',       #   small i, dieresis or umlaut mark
  97.     "Ntilde"    =>      '\\~{N}',       #   capital N, tilde
  98.     "ntilde"    =>      '\\~{n}',       #   small n, tilde
  99.     "Oacute"    =>      "\\'{O}",       #   capital O, acute accent
  100.     "oacute"    =>      "\\'{o}",       #   small o, acute accent
  101.     "Ocirc"     =>      "\\^{O}",       #   capital O, circumflex accent
  102.     "ocirc"     =>      "\\^{o}",       #   small o, circumflex accent
  103.     "Ograve"    =>      "\\`{O}",       #   capital O, grave accent
  104.     "ograve"    =>      "\\`{o}",       #   small o, grave accent
  105.     "Oslash"    =>      "\\O",          #   capital O, slash
  106.     "oslash"    =>      "\\o",          #   small o, slash
  107.     "Otilde"    =>      "\\~{O}",       #   capital O, tilde
  108.     "otilde"    =>      "\\~{o}",       #   small o, tilde
  109.     "Ouml"      =>      '\\"{O}',       #   capital O, dieresis or umlaut mark
  110.     "ouml"      =>      '\\"{o}',       #   small o, dieresis or umlaut mark
  111.     "szlig"     =>      '\\ss{}',       #   small sharp s, German (sz ligature)
  112.     "THORN"     =>      '\\L',          #   capital THORN, Icelandic
  113.     "thorn"     =>      '\\l',,         #   small thorn, Icelandic
  114.     "Uacute"    =>      "\\'{U}",       #   capital U, acute accent
  115.     "uacute"    =>      "\\'{u}",       #   small u, acute accent
  116.     "Ucirc"     =>      "\\^{U}",       #   capital U, circumflex accent
  117.     "ucirc"     =>      "\\^{u}",       #   small u, circumflex accent
  118.     "Ugrave"    =>      "\\`{U}",       #   capital U, grave accent
  119.     "ugrave"    =>      "\\`{u}",       #   small u, grave accent
  120.     "Uuml"      =>      '\\"{U}',       #   capital U, dieresis or umlaut mark
  121.     "uuml"      =>      '\\"{u}',       #   small u, dieresis or umlaut mark
  122.     "Yacute"    =>      "\\'{Y}",       #   capital Y, acute accent
  123.     "yacute"    =>      "\\'{y}",       #   small y, acute accent
  124.     "yuml"      =>      '\\"{y}',       #   small y, dieresis or umlaut mark
  125.  
  126.     # Added by TimJ
  127.  
  128.     "iexcl"  =>   '!`',           # inverted exclamation mark
  129. #    "cent"   =>   ' ',        # cent sign
  130.     "pound"  =>   '\pounds',      # (UK) pound sign
  131. #    "curren" =>   ' ',        # currency sign
  132. #    "yen"    =>   ' ',        # yen sign
  133. #    "brvbar" =>   ' ',        # broken vertical bar
  134.     "sect"   =>   '\S',           # section sign
  135.     "uml"    =>   '\"{}',        # diaresis
  136.     "copy"   =>   '\copyright',   # Copyright symbol
  137. #    "ordf"   =>   ' ',        # feminine ordinal indicator
  138.     "laquo"  =>   '$\ll$',      # ' # left pointing double angle quotation mark
  139.     "not"    =>   '$\neg$',       # '  # not sign
  140.     "shy"    =>   '-',            # soft hyphen
  141. #    "reg"    =>   ' ',        # registered trademark
  142.     "macr"   =>   '$^-$',         # ' # macron, overline
  143.     "deg"    =>   '$^\circ$',     # '  # degree sign
  144.     "plusmn" =>   '$\pm$',        # ' # plus-minus sign
  145.     "sup2"   =>   '$^2$',         # ' # superscript 2
  146.     "sup3"   =>   '$^3$',         # ' # superscript 3
  147.     "acute"  =>   "\\'{}",        # acute accent
  148.     "micro"  =>   '$\mu$',        # micro sign
  149.     "para"   =>   '\P',           # pilcrow sign = paragraph sign
  150.     "middot" =>   '$\cdot$',      # middle dot = Georgian comma
  151.     "cedil"  =>   '\c{}',        # cedilla
  152.     "sup1"   =>   '$^1$',         # ' # superscript 1
  153. #    "ordm"   =>   ' ',        # masculine ordinal indicator
  154.     "raquo"  =>   '$\gg$',     # ' # right pointing double angle quotation mark
  155.     "frac14" =>   '$\frac{1}{4}$',   # ' # vulgar fraction one quarter
  156.     "frac12" =>   '$\frac{1}{2}$',   # ' # vulgar fraction one half
  157.     "frac34" =>   '$\frac{3}{4}$',   # ' # vulgar fraction three quarters
  158.     "iquest" =>   "?'",              # inverted question mark
  159.     "times"  =>   '$\times$',        # ' # multiplication sign
  160.     "divide" =>   '$\div$',          # division sign
  161.  
  162.     # Greek letters using HTML codes
  163.     "alpha"  =>   '$\alpha$',   # '
  164.     "beta"   =>   '$\beta$',    # '
  165.     "gamma"  =>   '$\gamma$',   # '
  166.     "delta"  =>   '$\delta$',   # '
  167.     "epsilon"=>   '$\epsilon$', # '
  168.     "zeta"   =>   '$\zeta$',    # '
  169.     "eta"    =>   '$\eta$',     # '
  170.     "theta"  =>   '$\theta$',   # '
  171.     "iota"   =>   '$\iota$',    # '
  172.     "kappa"  =>   '$\kappa$',   # '
  173.     "lambda" =>   '$\lambda$',  # '
  174.     "mu"     =>   '$\mu$',      # '
  175.     "nu"     =>   '$\nu$',      # '
  176.     "xi"     =>   '$\xi$',      # '
  177.     "omicron"=>   '$o$',        # '
  178.     "pi"     =>   '$\pi$',      # '
  179.     "rho"    =>   '$\rho$',     # '
  180.     "sigma"  =>   '$\sigma$',   # '
  181.     "tau"    =>   '$\tau$',     # '
  182.     "upsilon"=>   '$\upsilon$', # '
  183.     "phi"    =>   '$\phi$',     # '
  184.     "chi"    =>   '$\chi$',     # '
  185.     "psi"    =>   '$\psi$',     # '
  186.     "omega"  =>   '$\omega$',   # '
  187.  
  188.     "Alpha"  =>   '$A$',   # '
  189.     "Beta"   =>   '$B$',    # '
  190.     "Gamma"  =>   '$\Gamma$',   # '
  191.     "Delta"  =>   '$\Delta$',   # '
  192.     "Epsilon"=>   '$E$', # '
  193.     "Zeta"   =>   '$Z$',    # '
  194.     "Eta"    =>   '$H$',     # '
  195.     "Theta"  =>   '$\Theta$',   # '
  196.     "Iota"   =>   '$I$',    # '
  197.     "Kappa"  =>   '$K$',   # '
  198.     "Lambda" =>   '$\Lambda$',  # '
  199.     "Mu"     =>   '$M$',      # '
  200.     "Nu"     =>   '$N$',      # '
  201.     "Xi"     =>   '$\Xi$',      # '
  202.     "Omicron"=>   '$O$',        # '
  203.     "Pi"     =>   '$\Pi$',      # '
  204.     "Rho"    =>   '$R$',     # '
  205.     "Sigma"  =>   '$\Sigma$',   # '
  206.     "Tau"    =>   '$T$',     # '
  207.     "Upsilon"=>   '$\Upsilon$', # '
  208.     "Phi"    =>   '$\Phi$',     # '
  209.     "Chi"    =>   '$X$',     # '
  210.     "Psi"    =>   '$\Psi$',     # '
  211.     "Omega"  =>   '$\Omega$',   # '
  212.  
  213.  
  214. );
  215.  
  216.  
  217. =head1 OBJECT METHODS
  218.  
  219. The following methods are provided in this module. Methods inherited
  220. from C<Pod::Select> are not described in the public interface.
  221.  
  222. =over 4
  223.  
  224. =begin __PRIVATE__
  225.  
  226. =item C<initialize>
  227.  
  228. Initialise the object. This method is subclassed from C<Pod::Parser>.
  229. The base class method is invoked. This method defines the default
  230. behaviour of the object unless overridden by supplying arguments to
  231. the constructor. 
  232.  
  233. Internal settings are defaulted as well as the public instance data.
  234. Internal hash values are accessed directly (rather than through
  235. a method) and start with an underscore.
  236.  
  237. This method should not be invoked by the user directly.
  238.  
  239. =end __PRIVATE__
  240.  
  241. =cut
  242.  
  243.  
  244.  
  245. #   - An array for nested lists
  246.  
  247. # Arguments have already been read by this point
  248.  
  249. sub initialize {
  250.   my $self = shift;
  251.  
  252.   # print Dumper($self);
  253.  
  254.   # Internals
  255.   $self->{_Lists} = [];             # For nested lists
  256.   $self->{_suppress_all_para}  = 0; # For =begin blocks
  257.   $self->{_suppress_next_para} = 0; # For =for blocks
  258.   $self->{_dont_modify_any_para}=0; # For =begin blocks
  259.   $self->{_dont_modify_next_para}=0; # For =for blocks
  260.   $self->{_CURRENT_HEAD1}   = '';   # Name of current HEAD1 section
  261.  
  262.   # Options - only initialise if not already set
  263.  
  264.   # Cause the '=head1 NAME' field to be treated specially
  265.   # The contents of the NAME paragraph will be converted
  266.   # to a section title. All subsequent =head1 will be converted
  267.   # to =head2 and down. Will not affect =head1's prior to NAME 
  268.   # Assumes:  'Module - purpose' format
  269.   # Also creates a purpose field
  270.   # The name is used for Labeling of the subsequent subsections
  271.   $self->{ReplaceNAMEwithSection} = 0
  272.     unless exists $self->{ReplaceNAMEwithSection};
  273.   $self->{AddPreamble}      = 1    # make full latex document
  274.     unless exists $self->{AddPreamble};
  275.   $self->{StartWithNewPage} = 0    # Start new page for pod section
  276.     unless exists $self->{StartWithNewPage};
  277.   $self->{TableOfContents}  = 0    # Add table of contents
  278.     unless exists $self->{TableOfContents};  # only relevent if AddPreamble=1
  279.    $self->{AddPostamble}     = 1          # Add closing latex code at end
  280.     unless exists $self->{AddPostamble}; #  effectively end{document} and index
  281.   $self->{MakeIndex}        = 1         # Add index (only relevant AddPostamble
  282.     unless exists $self->{MakeIndex};   # and AddPreamble)
  283.  
  284.   $self->{UniqueLabels}     = 1          # Use label unique for each pod
  285.     unless exists $self->{UniqueLabels}; # either based on the filename
  286.                                          # or supplied
  287.  
  288.   # Control the level of =head1. default is \section
  289.   # 
  290.   $self->{Head1Level}     = 1   # Offset in latex sections
  291.     unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection
  292.  
  293.   # Control at which level numbering of sections is turned off
  294.   # ie subsection becomes subsection*
  295.   # The numbering is relative to the latex sectioning commands
  296.   # and is independent of Pod heading level
  297.   # default is to number \section but not \subsection
  298.   $self->{LevelNoNum} = 2
  299.     unless exists $self->{LevelNoNum};
  300.  
  301.   # Label to be used as prefix to all internal section names
  302.   # If not defined will attempt to derive it from the filename
  303.   # This can not happen when running parse_from_filehandle though
  304.   # hence the ability to set the label externally
  305.   # The label could then be Pod::Parser_DESCRIPTION or somesuch
  306.  
  307.   $self->{Label}            = undef # label to be used as prefix
  308.     unless exists $self->{Label};   # to all internal section names
  309.  
  310.   # These allow the caller to add arbritrary latex code to
  311.   # start and end of document. AddPreamble and AddPostamble are ignored
  312.   # if these are set.
  313.   # Also MakeIndex and TableOfContents are also ignored.
  314.   $self->{UserPreamble}     = undef # User supplied start (AddPreamble =1)
  315.     unless exists $self->{Label};
  316.   $self->{UserPostamble}    = undef # Use supplied end    (AddPostamble=1)
  317.     unless exists $self->{Label};
  318.  
  319.   # Run base initialize
  320.   $self->SUPER::initialize;
  321.  
  322. }
  323.  
  324. =back
  325.  
  326. =head2 Data Accessors
  327.  
  328. The following methods are provided for accessing instance data. These
  329. methods should be used for accessing configuration parameters rather
  330. than assuming the object is a hash.
  331.  
  332. Default values can be supplied by using these names as keys to a hash
  333. of arguments when using the C<new()> constructor.
  334.  
  335. =over 4
  336.  
  337. =item B<AddPreamble>
  338.  
  339. Logical to control whether a C<latex> preamble is to be written.
  340. If true, a valid C<latex> preamble is written before the pod data is written.
  341. This is similar to:
  342.  
  343.   \documentclass{article}
  344.   \begin{document}
  345.  
  346. but will be more complicated if table of contents and indexing are required.
  347. Can be used to set or retrieve the current value.
  348.  
  349.   $add = $parser->AddPreamble();
  350.   $parser->AddPreamble(1);
  351.  
  352. If used in conjunction with C<AddPostamble> a full latex document will
  353. be written that could be immediately processed by C<latex>.
  354.  
  355. =cut
  356.  
  357. sub AddPreamble {
  358.    my $self = shift;
  359.    if (@_) {
  360.      $self->{AddPreamble} = shift;
  361.    }
  362.    return $self->{AddPreamble};
  363. }
  364.  
  365. =item B<AddPostamble>
  366.  
  367. Logical to control whether a standard C<latex> ending is written to the output
  368. file after the document has been processed.
  369. In its simplest form this is simply:
  370.  
  371.   \end{document}
  372.  
  373. but can be more complicated if a index is required.
  374. Can be used to set or retrieve the current value.
  375.  
  376.   $add = $parser->AddPostamble();
  377.   $parser->AddPostamble(1);
  378.  
  379. If used in conjunction with C<AddPreaamble> a full latex document will
  380. be written that could be immediately processed by C<latex>.
  381.  
  382. =cut
  383.  
  384. sub AddPostamble {
  385.    my $self = shift;
  386.    if (@_) {
  387.      $self->{AddPostamble} = shift;
  388.    }
  389.    return $self->{AddPostamble};
  390. }
  391.  
  392. =item B<Head1Level>
  393.  
  394. The C<latex> sectioning level that should be used to correspond to
  395. a pod C<=head1> directive. This can be used, for example, to turn
  396. a C<=head1> into a C<latex> C<subsection>. This should hold a number
  397. corresponding to the required position in an array containing the
  398. following elements:
  399.  
  400.  [0] chapter
  401.  [1] section
  402.  [2] subsection
  403.  [3] subsubsection
  404.  [4] paragraph
  405.  [5] subparagraph
  406.  
  407. Can be used to set or retrieve the current value:
  408.  
  409.   $parser->Head1Level(2);
  410.   $sect = $parser->Head1Level;
  411.  
  412. Setting this number too high can result in sections that may not be reproducible
  413. in the expected way. For example, setting this to 4 would imply that C<=head3>
  414. do not have a corresponding C<latex> section (C<=head1> would correspond to
  415. a C<paragraph>).
  416.  
  417. A check is made to ensure that the supplied value is an integer in the
  418. range 0 to 5.
  419.  
  420. Default is for a value of 1 (i.e. a C<section>).
  421.  
  422. =cut
  423.  
  424. sub Head1Level {
  425.    my $self = shift;
  426.    if (@_) {
  427.      my $arg = shift;
  428.      if ($arg =~ /^\d$/ && $arg <= $#LatexSections) {
  429.        $self->{Head1Level} = $arg;
  430.      } else {
  431.        carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n";
  432.      }
  433.    }
  434.    return $self->{Head1Level};
  435. }
  436.  
  437. =item B<Label>
  438.  
  439. This is the label that is prefixed to all C<latex> label and index
  440. entries to make them unique. In general, pods have similarly titled
  441. sections (NAME, DESCRIPTION etc) and a C<latex> label will be multiply
  442. defined if more than one pod document is to be included in a single
  443. C<latex> file. To overcome this, this label is prefixed to a label
  444. whenever a label is required (joined with an underscore) or to an
  445. index entry (joined by an exclamation mark which is the normal index
  446. separator). For example, C<\label{text}> becomes C<\label{Label_text}>.
  447.  
  448. Can be used to set or retrieve the current value:
  449.  
  450.   $label = $parser->Label;
  451.   $parser->Label($label);
  452.  
  453. This label is only used if C<UniqueLabels> is true.
  454. Its value is set automatically from the C<NAME> field
  455. if C<ReplaceNAMEwithSection> is true. If this is not the case
  456. it must be set manually before starting the parse.
  457.  
  458. Default value is C<undef>.
  459.  
  460. =cut
  461.  
  462. sub Label {
  463.    my $self = shift;
  464.    if (@_) {
  465.      $self->{Label} = shift;
  466.    }
  467.    return $self->{Label};
  468. }
  469.  
  470. =item B<LevelNoNum>
  471.  
  472. Control the point at which C<latex> section numbering is turned off.
  473. For example, this can be used to make sure that C<latex> sections
  474. are numbered but subsections are not.
  475.  
  476. Can be used to set or retrieve the current value:
  477.  
  478.   $lev = $parser->LevelNoNum;
  479.   $parser->LevelNoNum(2);
  480.  
  481. The argument must be an integer between 0 and 5 and is the same as the
  482. number described in C<Head1Level> method description. The number has
  483. nothing to do with the pod heading number, only the C<latex> sectioning.
  484.  
  485. Default is 2. (i.e. C<latex> subsections are written as C<subsection*>
  486. but sections are numbered).
  487.  
  488. =cut
  489.  
  490. sub LevelNoNum {
  491.    my $self = shift;
  492.    if (@_) {
  493.      $self->{LevelNoNum} = shift;
  494.    }
  495.    return $self->{LevelNoNum};
  496. }
  497.  
  498. =item B<MakeIndex>
  499.  
  500. Controls whether C<latex> commands for creating an index are to be inserted
  501. into the preamble and postamble
  502.  
  503.   $makeindex = $parser->MakeIndex;
  504.   $parser->MakeIndex(0);
  505.  
  506. Irrelevant if both C<AddPreamble> and C<AddPostamble> are false (or equivalently,
  507. C<UserPreamble> and C<UserPostamble> are set).
  508.  
  509. Default is for an index to be created.
  510.  
  511. =cut
  512.  
  513. sub MakeIndex {
  514.    my $self = shift;
  515.    if (@_) {
  516.      $self->{MakeIndex} = shift;
  517.    }
  518.    return $self->{MakeIndex};
  519. }
  520.  
  521. =item B<ReplaceNAMEwithSection>
  522.  
  523. This controls whether the C<NAME> section in the pod is to be translated
  524. literally or converted to a slightly modified output where the section
  525. name is the pod name rather than "NAME".
  526.  
  527. If true, the pod segment
  528.  
  529.   =head1 NAME
  530.  
  531.   pod::name - purpose
  532.  
  533.   =head1 SYNOPSIS
  534.  
  535. is converted to the C<latex>
  536.  
  537.   \section{pod::name\label{pod_name}\index{pod::name}}
  538.  
  539.   Purpose
  540.  
  541.   \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
  542.                \index{pod::name!SYNOPSIS}}
  543.  
  544. (dependent on the value of C<Head1Level> and C<LevelNoNum>). Note that
  545. subsequent C<head1> directives translate to subsections rather than
  546. sections and that the labels and index now include the pod name (dependent
  547. on the value of C<UniqueLabels>).
  548.  
  549. The C<Label> is set from the pod name regardless of any current value
  550. of C<Label>.
  551.  
  552.   $mod = $parser->ReplaceNAMEwithSection;
  553.   $parser->ReplaceNAMEwithSection(0);
  554.  
  555. Default is to translate the pod literally.
  556.  
  557. =cut
  558.  
  559. sub ReplaceNAMEwithSection {
  560.    my $self = shift;
  561.    if (@_) {
  562.      $self->{ReplaceNAMEwithSection} = shift;
  563.    }
  564.    return $self->{ReplaceNAMEwithSection};
  565. }
  566.  
  567. =item B<StartWithNewPage>
  568.  
  569. If true, each pod translation will begin with a C<latex>
  570. C<\clearpage>.
  571.  
  572.   $parser->StartWithNewPage(1);
  573.   $newpage = $parser->StartWithNewPage;
  574.  
  575. Default is false.
  576.  
  577. =cut
  578.  
  579. sub StartWithNewPage {
  580.    my $self = shift;
  581.    if (@_) {
  582.      $self->{StartWithNewPage} = shift;
  583.    }
  584.    return $self->{StartWithNewPage};
  585. }
  586.  
  587. =item B<TableOfContents>
  588.  
  589. If true, a table of contents will be created.
  590. Irrelevant if C<AddPreamble> is false or C<UserPreamble>
  591. is set.
  592.  
  593.   $toc = $parser->TableOfContents;
  594.   $parser->TableOfContents(1);
  595.  
  596. Default is false.
  597.  
  598. =cut
  599.  
  600. sub TableOfContents {
  601.    my $self = shift;
  602.    if (@_) {
  603.      $self->{TableOfContents} = shift;
  604.    }
  605.    return $self->{TableOfContents};
  606. }
  607.  
  608. =item B<UniqueLabels>
  609.  
  610. If true, the translator will attempt to make sure that
  611. each C<latex> label or index entry will be uniquely identified
  612. by prefixing the contents of C<Label>. This allows
  613. multiple documents to be combined without clashing 
  614. common labels such as C<DESCRIPTION> and C<SYNOPSIS>
  615.  
  616.   $parser->UniqueLabels(1);
  617.   $unq = $parser->UniqueLabels;
  618.  
  619. Default is true.
  620.  
  621. =cut
  622.  
  623. sub UniqueLabels {
  624.    my $self = shift;
  625.    if (@_) {
  626.      $self->{UniqueLabels} = shift;
  627.    }
  628.    return $self->{UniqueLabels};
  629. }
  630.  
  631. =item B<UserPreamble>
  632.  
  633. User supplied C<latex> preamble. Added before the pod translation
  634. data. 
  635.  
  636. If set, the contents will be prepended to the output file before the translated 
  637. data regardless of the value of C<AddPreamble>.
  638. C<MakeIndex> and C<TableOfContents> will also be ignored.
  639.  
  640. =cut
  641.  
  642. sub UserPreamble {
  643.    my $self = shift;
  644.    if (@_) {
  645.      $self->{UserPreamble} = shift;
  646.    }
  647.    return $self->{UserPreamble};
  648. }
  649.  
  650. =item B<UserPostamble>
  651.  
  652. User supplied C<latex> postamble. Added after the pod translation
  653. data. 
  654.  
  655. If set, the contents will be prepended to the output file after the translated 
  656. data regardless of the value of C<AddPostamble>.
  657. C<MakeIndex> will also be ignored.
  658.  
  659. =cut
  660.  
  661. sub UserPostamble {
  662.    my $self = shift;
  663.    if (@_) {
  664.      $self->{UserPostamble} = shift;
  665.    }
  666.    return $self->{UserPostamble};
  667. }
  668.  
  669. =begin __PRIVATE__
  670.  
  671. =item B<Lists>
  672.  
  673. Contains details of the currently active lists.
  674.   The array contains C<Pod::List> objects. A new C<Pod::List>
  675. object is created each time a list is encountered and it is
  676. pushed onto this stack. When the list context ends, it 
  677. is popped from the stack. The array will be empty if no
  678. lists are active.
  679.  
  680. Returns array of list information in list context
  681. Returns array ref in scalar context
  682.  
  683. =cut
  684.  
  685.  
  686.  
  687. sub lists {
  688.   my $self = shift;
  689.   return @{ $self->{_Lists} } if wantarray();
  690.   return $self->{_Lists};
  691. }
  692.  
  693. =end __PRIVATE__
  694.  
  695. =back
  696.  
  697. =begin __PRIVATE__
  698.  
  699. =head2 Subclassed methods
  700.  
  701. The following methods override methods provided in the C<Pod::Select>
  702. base class. See C<Pod::Parser> and C<Pod::Select> for more information
  703. on what these methods require.
  704.  
  705. =over 4
  706.  
  707. =cut
  708.  
  709. ######### END ACCESSORS ###################
  710.  
  711. # Opening pod
  712.  
  713. =item B<begin_pod>
  714.  
  715. Writes the C<latex> preamble if requested.
  716.  
  717. =cut
  718.  
  719. sub begin_pod {
  720.   my $self = shift;
  721.  
  722.   # Get the pod identification
  723.   # This should really come from the '=head1 NAME' paragraph
  724.  
  725.   my $infile = $self->input_file;
  726.   my $class = ref($self);
  727.   my $date = gmtime(time);
  728.  
  729.   # Comment message to say where this came from
  730.   my $comment = << "__TEX_COMMENT__";
  731. %%  Latex generated from POD in document $infile
  732. %%  Using the perl module $class
  733. %%  Converted on $date
  734. __TEX_COMMENT__
  735.  
  736.   # Write the preamble
  737.   # If the caller has supplied one then we just use that
  738.  
  739.   my $preamble = '';
  740.   if (defined $self->UserPreamble) {
  741.  
  742.     $preamble = $self->UserPreamble;
  743.  
  744.     # Add the description of where this came from
  745.     $preamble .=  "\n$comment";
  746.     
  747.  
  748.   } elsif ($self->AddPreamble) {
  749.     # Write our own preamble
  750.  
  751.     # Code to initialise index making
  752.     # Use an array so that we can prepend comment if required
  753.     my @makeidx = (
  754.            '\usepackage{makeidx}',
  755.            '\makeindex',
  756.           );
  757.  
  758.     unless ($self->MakeIndex) {
  759.       foreach (@makeidx) {
  760.     $_ = '%% ' . $_;
  761.       }
  762.     }
  763.     my $makeindex = join("\n",@makeidx) . "\n";
  764.  
  765.  
  766.     # Table of contents
  767.     my $tableofcontents = '\tableofcontents';
  768.     
  769.     $tableofcontents = '%% ' . $tableofcontents
  770.       unless $self->TableOfContents;
  771.  
  772.     # Roll our own
  773.     $preamble = << "__TEX_HEADER__";
  774. \\documentclass{article}
  775.  
  776. $comment
  777.  
  778. $makeindex
  779.  
  780. \\begin{document}
  781.  
  782. $tableofcontents
  783.  
  784. __TEX_HEADER__
  785.  
  786.   }
  787.  
  788.   # Write the header (blank if none)
  789.   $self->_output($preamble);
  790.  
  791.   # Start on new page if requested
  792.   $self->_output("\\clearpage\n") if $self->StartWithNewPage;
  793.  
  794. }
  795.  
  796.  
  797. =item B<end_pod>
  798.  
  799. Write the closing C<latex> code.
  800.  
  801. =cut
  802.  
  803. sub end_pod {
  804.   my $self = shift;
  805.  
  806.   # End string
  807.   my $end = '';
  808.  
  809.   # Use the user version of the postamble if deinfed
  810.   if (defined $self->UserPostamble) {
  811.     $end = $self->UserPostamble;
  812.  
  813.     $self->_output($end);
  814.  
  815.   } elsif ($self->AddPostamble) {
  816.  
  817.     # Check for index
  818.     my $makeindex = '\printindex';
  819.  
  820.     $makeindex = '%% '. $makeindex  unless $self->MakeIndex;
  821.  
  822.     $end = "$makeindex\n\n\\end{document}\n";
  823.   }
  824.  
  825.  
  826.   $self->_output($end);
  827.  
  828. }
  829.  
  830. =item B<command>
  831.  
  832. Process basic pod commands.
  833.  
  834. =cut
  835.  
  836. sub command {
  837.   my $self = shift;
  838.   my ($command, $paragraph, $line_num, $parobj) = @_;
  839.  
  840.   # return if we dont care
  841.   return if $command eq 'pod';
  842.  
  843.   $paragraph = $self->_replace_special_chars($paragraph);
  844.  
  845.   # Interpolate pod sequences in paragraph
  846.   $paragraph = $self->interpolate($paragraph, $line_num);
  847.  
  848.   $paragraph =~ s/\s+$//;
  849.  
  850.   # Now run the command
  851.   if ($command eq 'over') {
  852.  
  853.     $self->begin_list($paragraph, $line_num);
  854.  
  855.   } elsif ($command eq 'item') {
  856.  
  857.     $self->add_item($paragraph, $line_num);
  858.  
  859.   } elsif ($command eq 'back') {
  860.  
  861.     $self->end_list($line_num);
  862.  
  863.   } elsif ($command eq 'head1') {
  864.  
  865.     # Store the name of the section
  866.     $self->{_CURRENT_HEAD1} = $paragraph;
  867.  
  868.     # Print it
  869.     $self->head(1, $paragraph, $parobj);
  870.  
  871.   } elsif ($command eq 'head2') {
  872.  
  873.     $self->head(2, $paragraph, $parobj);
  874.  
  875.   } elsif ($command eq 'head3') {
  876.  
  877.     $self->head(3, $paragraph, $parobj);
  878.  
  879.   } elsif ($command eq 'head4') {
  880.  
  881.     $self->head(4, $paragraph, $parobj);
  882.  
  883.   } elsif ($command eq 'head5') {
  884.  
  885.     $self->head(5, $paragraph, $parobj);
  886.  
  887.   } elsif ($command eq 'head6') {
  888.  
  889.     $self->head(6, $paragraph, $parobj);
  890.  
  891.   } elsif ($command eq 'begin') {
  892.  
  893.     # pass through if latex
  894.     if ($paragraph =~ /^latex/i) {
  895.       # Make sure that subsequent paragraphs are not modfied before printing
  896.       $self->{_dont_modify_any_para} = 1;
  897.  
  898.     } else {
  899.       # Suppress all subsequent paragraphs unless 
  900.       # it is explcitly intended for latex
  901.       $self->{_suppress_all_para} = 1;
  902.     }
  903.  
  904.   } elsif ($command eq 'for') {
  905.  
  906.     # pass through if latex
  907.     if ($paragraph =~ /^latex/i) {
  908.       # Make sure that next paragraph is not modfied before printing
  909.       $self->{_dont_modify_next_para} = 1;
  910.  
  911.     } else {
  912.       # Suppress the next paragraph unless it is latex
  913.       $self->{_suppress_next_para} = 1
  914.     }
  915.  
  916.   } elsif ($command eq 'end') {
  917.  
  918.     # Reset suppression
  919.     $self->{_suppress_all_para} = 0;
  920.     $self->{_dont_modify_any_para} = 0;
  921.  
  922.   } elsif ($command eq 'pod') {
  923.  
  924.     # Do nothing
  925.  
  926.   } else {
  927.     carp "Command $command not recognised at line $line_num\n";
  928.   }
  929.  
  930. }
  931.  
  932. =item B<verbatim>
  933.  
  934. Verbatim text
  935.  
  936. =cut
  937.  
  938. sub verbatim {
  939.   my $self = shift;
  940.   my ($paragraph, $line_num, $parobj) = @_;
  941.  
  942.   # Expand paragraph unless in =for or =begin block
  943.   if ($self->{_dont_modify_any_para} || $self->{_dont_modify_next_para}) {
  944.     # Just print as is
  945.     $self->_output($paragraph);
  946.  
  947.     # Reset flag if in =for
  948.     $self->{_dont_modify_next_para} = 0;
  949.  
  950.   } else {
  951.  
  952.     return if $paragraph =~ /^\s+$/;
  953.  
  954.     # Clean trailing space
  955.     $paragraph =~ s/\s+$//;
  956.  
  957.     # Clean tabs
  958.     $paragraph =~ s/\t/        /g;
  959.  
  960.     $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n");
  961.   }
  962. }
  963.  
  964. =item B<textblock>
  965.  
  966. Plain text paragraph.
  967.  
  968. =cut
  969.  
  970. sub textblock {
  971.   my $self = shift;
  972.   my ($paragraph, $line_num, $parobj) = @_;
  973.  
  974.   # print Dumper($self);
  975.   
  976.   # Expand paragraph unless in =for or =begin block
  977.   if ($self->{_dont_modify_any_para} || $self->{_dont_modify_next_para}) {
  978.     # Just print as is
  979.     $self->_output($paragraph);
  980.  
  981.     # Reset flag if in =for
  982.     $self->{_dont_modify_next_para} = 0;
  983.  
  984.     return;
  985.   } 
  986.  
  987.   
  988.   # Escape latex special characters
  989.   $paragraph = $self->_replace_special_chars($paragraph);
  990.  
  991.   # Interpolate interior sequences
  992.   my $expansion = $self->interpolate($paragraph, $line_num);
  993.   $expansion =~ s/\s+$//;
  994.  
  995.  
  996.   # If we are replacing 'head1 NAME' with a section
  997.   # we need to look in the paragraph and rewrite things
  998.   # Need to make sure this is called only on the first paragraph
  999.   # following 'head1 NAME' and not on subsequent paragraphs that may be
  1000.   # present.
  1001.   if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) {
  1002.  
  1003.     # Strip white space from start and end
  1004.     $paragraph =~ s/^\s+//;
  1005.     $paragraph =~ s/\s$//;
  1006.  
  1007.     # Split the string into 2 parts
  1008.     my ($name, $purpose) = split(/\s+-\s+/, $expansion,2);
  1009.  
  1010.     # Now prevent this from triggering until a new head1 NAME is set
  1011.     $self->{_CURRENT_HEAD1} = '_NAME';
  1012.  
  1013.     # Might want to clear the Label() before doing this (CHECK)
  1014.  
  1015.     # Print the heading
  1016.     $self->head(1, $name, $parobj);
  1017.  
  1018.     # Set the labeling in case we want unique names later
  1019.     $self->Label( $self->_create_label( $name, 1 ) );
  1020.  
  1021.     # Raise the Head1Level by one so that subsequent =head1 appear
  1022.     # as subsections of the main name section unless we are already
  1023.     # at maximum [Head1Level() could check this itself - CHECK]
  1024.     $self->Head1Level( $self->Head1Level() + 1)
  1025.       unless $self->Head1Level == $#LatexSections;
  1026.  
  1027.     # Now write out the new latex paragraph
  1028.     $purpose = ucfirst($purpose);
  1029.     $self->_output("\n\n$purpose\n\n");
  1030.  
  1031.   } else {
  1032.     # Just write the output
  1033.     $self->_output("\n\n$expansion\n\n");
  1034.   }
  1035.  
  1036. }
  1037.  
  1038. =item B<interior_sequence>
  1039.  
  1040. Interior sequence expansion
  1041.  
  1042. =cut
  1043.  
  1044. sub interior_sequence {
  1045.   my $self = shift;
  1046.  
  1047.   my ($seq_command, $seq_argument, $pod_seq) = @_;
  1048.  
  1049.   if ($seq_command eq 'B') {
  1050.     return "\\textbf{$seq_argument}";
  1051.  
  1052.   } elsif ($seq_command eq 'I') {
  1053.     return "\\textit{$seq_argument}";
  1054.  
  1055.   } elsif ($seq_command eq 'E') {
  1056.  
  1057.     # If it is simply a number
  1058.     if ($seq_argument =~ /^\d+$/) {
  1059.       return chr($seq_argument);
  1060.     # Look up escape in hash table
  1061.     } elsif (exists $HTML_Escapes{$seq_argument}) {
  1062.       return $HTML_Escapes{$seq_argument};
  1063.  
  1064.     } else {
  1065.       my ($file, $line) = $pod_seq->file_line();
  1066.       warn "Escape sequence $seq_argument not recognised at line $line of file $file\n";
  1067.       return;
  1068.     }
  1069.  
  1070.   } elsif ($seq_command eq 'Z') {
  1071.  
  1072.     # Zero width space
  1073.     return '$\!$'; # '
  1074.  
  1075.   } elsif ($seq_command eq 'C') {
  1076.     return "\\texttt{$seq_argument}";
  1077.  
  1078.   } elsif ($seq_command eq 'F') {
  1079.     return "\\emph{$seq_argument}";
  1080.  
  1081.   } elsif ($seq_command eq 'S') {
  1082.     # non breakable spaces
  1083.     my $nbsp = '$\:$'; #'
  1084.  
  1085.     $seq_argument =~ s/\s/$nbsp/g;
  1086.     return $seq_argument;
  1087.  
  1088.   } elsif ($seq_command eq 'L') {
  1089.  
  1090.     my $link = new Pod::Hyperlink($seq_argument);
  1091.  
  1092.     # undef on failure
  1093.     unless (defined $link) {
  1094.       carp $@;
  1095.       return;
  1096.     }
  1097.  
  1098.     # Handle internal links differently
  1099.     my $type = $link->type;
  1100.     my $page = $link->page;
  1101.  
  1102.     if ($type eq 'section' && $page eq '') {
  1103.       # Use internal latex reference 
  1104.       my $node = $link->node;
  1105.  
  1106.       # Convert to a label
  1107.       $node = $self->_create_label($node);
  1108.  
  1109.       return "\\S\\ref{$node}";
  1110.  
  1111.     } else {
  1112.       # Use default markup for external references
  1113.       # (although Starlink would use \xlabel)
  1114.       my $markup = $link->markup;
  1115.  
  1116.       my ($file, $line) = $pod_seq->file_line();
  1117.  
  1118.       return $self->interpolate($link->markup, $line);
  1119.     }
  1120.  
  1121.  
  1122.  
  1123.   } elsif ($seq_command eq 'P') {
  1124.     # Special markup for Pod::Hyperlink
  1125.     # Replace :: with /
  1126.     my $link = $seq_argument;
  1127.     $link =~ s/::/\//g;
  1128.  
  1129.     my $ref = "\\emph{$seq_argument}";
  1130.     return $ref;
  1131.  
  1132.   } elsif ($seq_command eq 'Q') {
  1133.     # Special markup for Pod::Hyperlink
  1134.     return "\\textsf{$seq_argument}\n";
  1135.  
  1136.   } elsif ($seq_command eq 'X') {
  1137.     # Index entries
  1138.  
  1139.     # use \index command
  1140.     # I will let '!' go through for now
  1141.     # not sure how sub categories are handled in X<>
  1142.     my $index = $self->_create_index($seq_argument);
  1143.     return "\\index{$index}\n";
  1144.  
  1145.   } else {
  1146.     carp "Unknown sequence $seq_command<$seq_argument>";
  1147.   }
  1148.  
  1149. }
  1150.  
  1151. =back
  1152.  
  1153. =head2 List Methods
  1154.  
  1155. Methods used to handle lists.
  1156.  
  1157. =over 4
  1158.  
  1159. =item B<begin_list>
  1160.  
  1161. Called when a new list is found (via the C<over> directive).
  1162. Creates a new C<Pod::List> object and stores it on the 
  1163. list stack.
  1164.  
  1165.   $parser->begin_list($indent, $line_num);
  1166.  
  1167. =cut
  1168.  
  1169. sub begin_list {
  1170.   my $self = shift;
  1171.   my $indent = shift;
  1172.   my $line_num = shift;
  1173.  
  1174.   # Indicate that a list should be started for the next item
  1175.   # need to do this to work out the type of list
  1176.   push ( @{$self->lists}, new Pod::List(-indent => $indent, 
  1177.                     -start => $line_num,
  1178.                     -file => $self->input_file,
  1179.                        )     
  1180.        );
  1181.  
  1182. }
  1183.  
  1184. =item B<end_list>
  1185.  
  1186. Called when the end of a list is found (the C<back> directive).
  1187. Pops the C<Pod::List> object off the stack of lists and writes
  1188. the C<latex> code required to close a list.
  1189.  
  1190.   $parser->end_list($line_num);
  1191.  
  1192. =cut
  1193.  
  1194. sub end_list {
  1195.   my $self = shift;
  1196.   my $line_num = shift;
  1197.  
  1198.   unless (defined $self->lists->[-1]) {
  1199.     my $file = $self->input_file;
  1200.     warn "No list is active at line $line_num (file=$file). Missing =over?\n";
  1201.     return;
  1202.   }
  1203.  
  1204.   # What to write depends on list type
  1205.   my $type = $self->lists->[-1]->type;
  1206.  
  1207.   # Dont write anything if the list type is not set
  1208.   # iomplying that a list was created but no entries were
  1209.   # placed in it (eg because of a =begin/=end combination)
  1210.   $self->_output("\\end{$type}\n")
  1211.     if (defined $type && length($type) > 0);
  1212.   
  1213.   # Clear list
  1214.   pop(@{ $self->lists});
  1215.  
  1216. }
  1217.  
  1218. =item B<add_item>
  1219.  
  1220. Add items to the list. The first time an item is encountered 
  1221. (determined from the state of the current C<Pod::List> object)
  1222. the type of list is determined (ordered, unnumbered or description)
  1223. and the relevant latex code issued.
  1224.  
  1225.   $parser->add_item($paragraph, $line_num);
  1226.  
  1227. =cut
  1228.  
  1229. sub add_item {
  1230.   my $self = shift;
  1231.   my $paragraph = shift;
  1232.   my $line_num = shift;
  1233.  
  1234.   unless (defined $self->lists->[-1]) {
  1235.     my $file = $self->input_file;
  1236.     warn "List has already ended by line $line_num of file $file. Missing =over?\n";
  1237.     # Replace special chars
  1238. #    $paragraph = $self->_replace_special_chars($paragraph);
  1239.     $self->_output("$paragraph\n\n");
  1240.     return;
  1241.   }
  1242.  
  1243.   # If paragraphs printing is turned off via =begin/=end or whatver
  1244.   # simply return immediately
  1245.   return if ($self->{_suppress_all_para} || $self->{_suppress_next_para});
  1246.  
  1247.   # Check to see whether we are starting a new lists
  1248.   if (scalar($self->lists->[-1]->item) == 0) {
  1249.  
  1250.     # Examine the paragraph to determine what type of list
  1251.     # we have
  1252.     $paragraph =~ s/\s+$//;
  1253.     $paragraph =~ s/^\s+//;
  1254.  
  1255.     my $type;
  1256.     if (substr($paragraph, 0,1) eq '*') {
  1257.       $type = 'itemize';
  1258.     } elsif ($paragraph =~ /^\d/) {
  1259.       $type = 'enumerate';
  1260.     } else {
  1261.       $type = 'description';
  1262.     }
  1263.     $self->lists->[-1]->type($type);
  1264.  
  1265.     $self->_output("\\begin{$type}\n");
  1266.  
  1267.   }
  1268.  
  1269.   my $type = $self->lists->[-1]->type;
  1270.  
  1271.   if ($type eq 'description') {
  1272.     # Handle long items - long items do not wrap
  1273.     if (length($paragraph) < 40) {
  1274.       # A real description list item
  1275.       $self->_output("\\item[$paragraph] \\mbox{}");
  1276.     } else {
  1277.       # The item is now simply bold text
  1278.       $self->_output(qq{\\item \\textbf{$paragraph}});
  1279.     }
  1280.  
  1281.   } else {
  1282.     # If the item was '* Something' we still need to write
  1283.     # out the something
  1284.     my $extra_info = $paragraph;
  1285.     $extra_info =~ s/^\*\s*//;
  1286.     $self->_output("\\item $extra_info");
  1287.   }
  1288.  
  1289.   # Store the item name in the object. Required so that 
  1290.   # we can tell if the list is new or not
  1291.   $self->lists->[-1]->item($paragraph);
  1292.  
  1293. }
  1294.  
  1295. =back
  1296.  
  1297. =head2 Methods for headings
  1298.  
  1299. =over 4
  1300.  
  1301. =item B<head>
  1302.  
  1303. Print a heading of the required level.
  1304.  
  1305.   $parser->head($level, $paragraph, $parobj);
  1306.  
  1307. The first argument is the pod heading level. The second argument
  1308. is the contents of the heading. The 3rd argument is a Pod::Paragraph
  1309. object so that the line number can be extracted.
  1310.  
  1311. =cut
  1312.  
  1313. sub head {
  1314.   my $self = shift;
  1315.   my $num = shift;
  1316.   my $paragraph = shift;
  1317.   my $parobj = shift;
  1318.  
  1319.   # If we are replace 'head1 NAME' with a section
  1320.   # we return immediately if we get it
  1321.   return 
  1322.     if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection());
  1323.  
  1324.   # Create a label
  1325.   my $label = $self->_create_label($paragraph);
  1326.  
  1327.   # Create an index entry
  1328.   my $index = $self->_create_index($paragraph);
  1329.  
  1330.   # Work out position in the above array taking into account
  1331.   # that =head1 is equivalent to $self->Head1Level
  1332.  
  1333.   my $level = $self->Head1Level() - 1 + $num;
  1334.  
  1335.   # Warn if heading to large
  1336.   if ($num > $#LatexSections) {
  1337.     my $line = $parobj->file_line;
  1338.     my $file = $self->input_file;
  1339.     warn "Heading level too large ($level) for LaTeX at line $line of file $file\n";
  1340.     $level = $#LatexSections;
  1341.   }
  1342.  
  1343.   # Check to see whether section should be unnumbered
  1344.   my $star = ($level >= $self->LevelNoNum ? '*' : '');
  1345.  
  1346.   # Section
  1347.   $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}");
  1348.  
  1349. }
  1350.  
  1351.  
  1352. =back
  1353.  
  1354. =end __PRIVATE__
  1355.  
  1356. =begin __PRIVATE__
  1357.  
  1358. =head2 Internal methods
  1359.  
  1360. Internal routines are described in this section. They do not form part of the
  1361. public interface. All private methods start with an underscore.
  1362.  
  1363. =over 4
  1364.  
  1365. =item B<_output>
  1366.  
  1367. Output text to the output filehandle. This method must be always be called
  1368. to output parsed text.
  1369.  
  1370.    $parser->_output($text);
  1371.  
  1372. Does not write anything if a =begin or =for is active that should be
  1373. ignored.
  1374.  
  1375. =cut
  1376.  
  1377. sub _output { 
  1378.   my $self = shift;
  1379.   my $text = shift;
  1380.  
  1381.   print { $self->output_handle } $text 
  1382.     unless $self->{_suppress_all_para} ||
  1383.       $self->{_suppress_next_para};
  1384.  
  1385.   # Reset pargraph stuff for =for
  1386.   $self->{_suppress_next_para} = 0
  1387.     if $self->{_suppress_next_para};
  1388. }
  1389.  
  1390.  
  1391. =item B<_replace_special_chars>
  1392.  
  1393. Subroutine to replace characters that are special in C<latex>
  1394. with the escaped forms
  1395.  
  1396.   $escaped = $parser->_replace_special_chars($paragraph);
  1397.  
  1398. Need to call this routine before interior_sequences are munged but
  1399. not if verbatim.
  1400.  
  1401. Special characters and the C<latex> equivalents are:
  1402.  
  1403.   }     \}
  1404.   {     \{
  1405.   _     \_
  1406.   $     \$
  1407.   %     \%
  1408.   &     \&
  1409.   \     $\backslash$
  1410.   ^     \^{}
  1411.   ~     \~{}
  1412.   |     $|$
  1413.  
  1414. =cut
  1415.  
  1416. sub _replace_special_chars {
  1417.   my $self = shift;
  1418.   my $paragraph = shift;
  1419.  
  1420.   # Replace a \ with $\backslash$
  1421.   # This is made more complicated because the dollars will be escaped
  1422.   # by the subsequent replacement. Easiest to add \backslash 
  1423.   # now and then add the dollars
  1424.   $paragraph =~ s/\\/\\backslash/g;
  1425.  
  1426.   # Must be done after escape of \ since this command adds latex escapes
  1427.   # Replace characters that can be escaped
  1428.   $paragraph =~ s/([\$\#&%_{}])/\\$1/g;
  1429.  
  1430.   # Replace ^ characters with \^{} so that $^F works okay
  1431.   $paragraph =~ s/(\^)/\\$1\{\}/g;
  1432.  
  1433.   # Replace tilde (~) with \texttt{\~{}}
  1434.   $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g;
  1435.  
  1436.   # Replace | with $|$
  1437.   $paragraph =~ s'\|'$|$'g;
  1438.  
  1439.   # Now add the dollars around each \backslash
  1440.   $paragraph =~ s/(\\backslash)/\$$1\$/g;
  1441.  
  1442.   return $paragraph;
  1443. }
  1444.  
  1445.  
  1446. =item B<_create_label>
  1447.  
  1448. Return a string that can be used as an internal reference
  1449. in a C<latex> document (i.e. accepted by the C<\label> command)
  1450.  
  1451.  $label = $parser->_create_label($string)
  1452.  
  1453. If UniqueLabels is true returns a label prefixed by Label()
  1454. This can be suppressed with an optional second argument.
  1455.  
  1456.  $label = $parser->_create_label($string, $suppress);
  1457.  
  1458. If a second argument is supplied (of any value including undef)
  1459. the Label() is never prefixed. This means that this routine can
  1460. be called to create a Label() without prefixing a previous setting.
  1461.  
  1462. =cut
  1463.  
  1464. sub _create_label {
  1465.   my $self = shift;
  1466.   my $paragraph = shift;
  1467.   my $suppress = (@_ ? 1 : 0 );
  1468.  
  1469.   # Remove latex commands
  1470.   $paragraph = $self->_clean_latex_commands($paragraph);
  1471.  
  1472.   # Remove non alphanumerics from the label and replace with underscores
  1473.   # want to protect '-' though so use negated character classes 
  1474.   $paragraph =~ s/[^-:\w]/_/g;
  1475.  
  1476.   # Multiple underscores will look unsightly so remove repeats
  1477.   # This will also have the advantage of tidying up the end and
  1478.   # start of string
  1479.   $paragraph =~ s/_+/_/g;
  1480.  
  1481.   # If required need to make sure that the label is unique
  1482.   # since it is possible to have multiple pods in a single
  1483.   # document
  1484.   if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
  1485.     $paragraph = $self->Label() .'_'. $paragraph;
  1486.   }
  1487.  
  1488.   return $paragraph;
  1489. }
  1490.  
  1491.  
  1492. =item B<_create_index>
  1493.  
  1494. Similar to C<_create_label> except an index entry is created.
  1495. If C<UniqueLabels> is true, the index entry is prefixed by 
  1496. the current C<Label> and an exclamation mark.
  1497.  
  1498.   $ind = $parser->_create_index($paragraph);
  1499.  
  1500. An exclamation mark is used by C<makeindex> to generate 
  1501. sub-entries in an index.
  1502.  
  1503. =cut
  1504.  
  1505. sub _create_index {
  1506.   my $self = shift;
  1507.   my $paragraph = shift;
  1508.   my $suppress = (@_ ? 1 : 0 );
  1509.  
  1510.   # Remove latex commands
  1511.   $paragraph = $self->_clean_latex_commands($paragraph);
  1512.  
  1513.   # If required need to make sure that the index entry is unique
  1514.   # since it is possible to have multiple pods in a single
  1515.   # document
  1516.   if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
  1517.     $paragraph = $self->Label() .'!'. $paragraph;
  1518.   }
  1519.  
  1520.   # Need to replace _ with space
  1521.   $paragraph =~ s/_/ /g;
  1522.  
  1523.   return $paragraph;
  1524.  
  1525. }
  1526.  
  1527. =item B<_clean_latex_commands>
  1528.  
  1529. Removes latex commands from text. The latex command is assumed to be of the
  1530. form C<\command{ text }>. "C<text>" is retained
  1531.  
  1532.   $clean = $parser->_clean_latex_commands($text);
  1533.  
  1534. =cut
  1535.  
  1536. sub _clean_latex_commands {
  1537.   my $self = shift;
  1538.   my $paragraph = shift;
  1539.  
  1540.   # Remove latex commands of the form \text{ }
  1541.   # and replace with the contents of the { }
  1542.   # need to make this non-greedy so that it can handle
  1543.   #  "\text{a} and \text2{b}"
  1544.   # without converting it to
  1545.   #  "a} and \text2{b"
  1546.   # This match will still get into trouble if \} is present 
  1547.   # This is not vital since the subsequent replacement of non-alphanumeric
  1548.   # characters will tidy it up anyway
  1549.   $paragraph =~ s/\\\w+{(.*?)}/$1/g;
  1550.  
  1551.   return $paragraph
  1552. }
  1553.  
  1554. =back
  1555.  
  1556. =end __PRIVATE__
  1557.  
  1558. =head1 NOTES
  1559.  
  1560. Compatible with C<latex2e> only. Can not be used with C<latex> v2.09
  1561. or earlier.
  1562.  
  1563. A subclass of C<Pod::Select> so that specific pod sections can be
  1564. converted to C<latex> by using the C<select> method.
  1565.  
  1566. Some HTML escapes are missing and many have not been tested.
  1567.  
  1568. =head1 SEE ALSO
  1569.  
  1570. L<Pod::Parser>, L<Pod::Select>, L<pod2latex>
  1571.  
  1572. =head1 AUTHORS
  1573.  
  1574. Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt>
  1575.  
  1576. =head1 COPYRIGHT
  1577.  
  1578. Copyright (C) 2000 Tim Jenness. All Rights Reserved.
  1579.  
  1580. This program is free software; you can redistribute it and/or modify it
  1581. under the same terms as Perl itself.
  1582.  
  1583. =begin __PRIVATE__
  1584.  
  1585. =head1 REVISION
  1586.  
  1587. $Id: LaTeX.pm,v 1.6 2000/08/21 09:05:03 timj Exp $
  1588.  
  1589. =end __PRIVATE__
  1590.  
  1591. =cut
  1592.